<?php
/**
 * Ruth Library
 * $Id: Generator.php 2 2008-01-17 02:59:56Z baron314159@yahoo.com $
 *
 * LICENSE
 *
 * Copyright (c) 2007, Chris Utz
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the Impact Lab nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY CHRIS UTZ ``AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL CHRIS UTZ BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * @category   Ruth
 * @package    Ruth_Message
 * @author     Chris Utz <chris@chrisutz.com>
 * @copyright  2007 Chris Utz <chris@chrisutz.com>
 * @license    http://www.opensource.org/licenses/bsd-license.php    New BSD License
 * @version    $Revision: 2 $
 */

/**
 * @see Ruth_Message_Exception
 */
require_once 'Ruth/Message/Exception.php';

/**
 * Interpolates an associative array's key => value pairs into a string.
 *
 * @category   Ruth
 * @package    Ruth_Message
 * @author     Chris Utz <chris@chrisutz.com>
 * @copyright  2007 Chris Utz <chris@chrisutz.com>
 * @license    http://www.opensource.org/licenses/bsd-license.php    New BSD License
 * @version    $Revision: 2 $
 */
class Ruth_Message_Generator
{
    /**
     * The template for the message.
     *
     * @var string
     */
    protected $_text = '';

    /**
     * Holds the variables passed into the run() method so that 
     * pregReplaceCallback can access them.
     *
     * @var array
     */
    protected $_variables = array();

    /**
     * Constructs a Ruth_Message_Generator object.
     *
     * @param string $text The template for the message.
     * @param array $variables The variables to interpolate into the message
     * @return void
     */
    public function __construct($text, array $variables = array())
    {
        $this->_text = $text;
        $this->_variables = $variables;
    }

    /**
     * Interpolates an array of key => value pairs into a string of text.
     * Substrings of the form %KEY% are replaced with the values associated
     * with keys of the form KEY. This method is just for convenience, it is
     * equivalent to:
     * $generator = new Ruth_Message_Generator();
     * $myMsg = $generator->run($text, $variables);
     *
     * @param string $text
     * @param array $variables
     * @return string
     */
    public static function generate($text, array $variables = array())
    {
        $generator = new Ruth_Message_Generator($text, $variables);
        return $generator->__toString();
    }

    /**
     * Interpolates an array of key => value pairs into a string of text.
     * Substrings of the form %KEY% are replaced with the values associated
     * with keys of the form KEY. The resultant text is this interpolated
     * printf-style into $outer.
     *
     * @param string $outer The message text is interpolated into this string.
     * @return string
     */
    public function printIn($outer = '%s')
    {
        $message = @preg_replace_callback('/%([a-zA-Z0-9]+)%/',
            array($this, 'pregReplaceCallback'), (string) $this->_text);

        return sprintf($outer, $message);
    }

    /**
     * Generates and returns the interpolated message.
     *
     * @return string
     */
    public function __toString()
    {
        return $this->printIn();
    }

    /**
     * A callback method used by preg_replace_callback. It is passed in an
     * array of matches (0 = %KEY%, 1 = KEY), and returns the replacement
     * from the _variables array.
     *
     * @param array $matches
     * @return string
     */
    public function pregReplaceCallback($matches)
    {
        if (isset($this->_variables[$matches[1]])) {
            return (string) $this->_variables[$matches[1]];
        } else {
            return '%' . $matches[1] . '%';
        }
    }
}
 
// vim: sw=4:ts=4:sts=4:et
